ODFrame

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODFrame

Superclasses
ODPersistentObject --> ODRefCntObject --> ODObject
Subclasses
none

An object of the ODFrame class describes the display area of an embedded part in the content of its containing part.

Description
A frame object represents an area of content of a part; it marks the geometric boundary between an embedded part and its containing part. There are several possible configurations and states for frames:

A part's display frame is a frame within which the part's content is drawn. Each display frame represents a particular view of a part's content.
A part's embedded frame is a frame within which one of the part's embedded parts is displayed.
A containing frame is a frame in which one or more frames is embedded. Each embedded frame has one containing frame; each containing frame has one or more embedded frames.
The root frame is the frame in which the root part of a window is displayed. The root frame shape is the same as the content area of the window.
The active frame is the frame that has the selection focus. Editing takes place in the active frame; that frame displays the selection or insertion point.
An overlaid frame is an embedded frame that floats above a containing part's content (including other embedded frames). Overlaid frames do not need to negotiate for space except as required by the constraints of the containing part size.
A subframe is a frame that is both an embedded frame in, and a display frame of, a part. A part can create an embedded frame, make it a subframe of its own display frame, and then display itself in that subframe. When a subframe has the selection focus, the active frame border is displayed around its containing frame.
A bundled frame is a frame whose content does not respond to geometry-based user events. A mouse click within a bundled frame selects the frame's part, but does not activate it.
A nonpersistent frame is a frame that exists as an in-memory object only. A nonpersistent frame does not have a storage unit and is not stored persistently.

Your part creates a new frame object for its embedded parts by calling its draft's CreateFrame method (page 163). Your part accesses a previously stored frame object by calling its draft's AcquireFrame method (page 152). These methods return a reference to a frame object.

Frame Geometry
There are several things that define the geometry of a frame.

The frame shape defines the area that the containing part propagates to an embedded part's display frame. The frame's containing part controls the frame shape.
The used shape defines the area of an embedded part's frame that has actual content to display, that is, the part of the frame that the containing part should not draw over. However, the containing part is free to wrap content to the contour of the used shape. The embedded part controls the used shape.
The internal transform describes how the part's content is positioned, scaled, or otherwise transformed within the frame. It represents the mapping from the coordinate space of the frame's content to the coordinate space of the frame.
The content extent describes how much offset is used to calculate the bias transform, that is, the vertical extent of the content area of a part in a frame (in essence, the height of a part's page). For more information related to bias transforms, see the ODCanvas class description (page 62).

A frame must always possess a valid frame shape. The used shape does not need to be set; if it is not, the used shape is the same as the frame shape. For more information related to shape objects, see the ODShape class description (page 629).
A frame must always possess a valid internal transform which, if not explicitly set, is the identity transform. For more information related to transform objects, see the ODTransform class description (page 762).
The ODFrame class includes several methods that specify geometry (shape and transform) objects. Because these objects necessarily assume a coordinate system, the ODFrame methods include a parameter, biasCanvas, that allows you to specify a canvas to whose coordinate space the geometry is biased. The bias canvas uses a bias transform to convert from the coordinate system used for drawing on the canvas to the coordinate system (platform-normal coordinates) used by the current graphics system. When the bias canvas is specified, it is automatically applied to the returned object.
Each part in an OpenDoc document controls the position, size, and shape of the frames embedded within it. At the same time, embedded parts may want to change the size, shape, or number of frames they are displayed in. Through a process called frame negotiation, an embedded part and its containing part agree on the frame or frames the embedded part displays in. Either part can initiate the negotiation, although the containing part has unilateral control over the outcome.

Frame Hierarchy
A frame always maintains a reference to its part. The frame ensures that it is registered with its part on that part's internal list of display frames when the frame is created (by calling its part's DisplayFrameAdded method (page 494)) and that it is removed from that part's internal list of display frames when the frame is deleted (by calling its part's DisplayFrameRemoved method (page 498)).
A frame maintains a reference to its containing frame. The value of the reference is null if the specified frame is the root frame of a window. The reference value does not usually change, unless the frame was created before an embedding location was selected. A frame does not hold direct references to its embedded frames. Only the frame's part knows which frames are embedded in the frame.
A frame maintains a list of its facets. Facets hold nonpersistent information about the layout of parts, or describe the location of a frame on a particular canvas for display and event dispatching. There may be more than one facet per frame. The list may be empty if the specified frame is currently scrolled out of view or otherwise not visible. For more information related to facet objects, see the ODFacet class description (page 219).

Display Information
There are two characteristics that describe how a part is displayed within a frame.

The view type describes the basic visual representation of a part. Parts must support the standard set of view types (large icon, small icon, thumbnail, or frame view). The view type should be set only by the frame's part.
The presentation of a frame describes, for parts whose view type is framed, a particular style of display for a part's content within the frame--for example, table, bar chart or pie chart, text or outline. Presentations are part-defined; your part editor determines what types of presentations your part is capable of, and defines a presentation designation for each. A containing part may request a particular presentation but the embedded part need not honor that request. The presentation should be set only by the frame's part.

A frame's part might store user-defined data in the frame's part info. The part alone interprets or manipulates the data, but the part info data is stored with the frame and read in only when it is necessary for frame manipulation.

Propagating Events
If one of your part's embedded frames propagates unhandled events to your part, your part has the opportunity to handle those events. In that case, your part's event handler needs to determine whether a particular frame is one of its display frames or an embedded frame.

Frame Groups
A frame group is a set of display frames that a part designates as related, for purposes such as flowing content from one frame to another. Each frame group has its own group ID; frames within a frame group have a sequence number that is used to define the position of a frame within its frame group. The group ID and sequence number should be set only by the frame's containing part.

Flags and Link Status
When a part creates a frame, the part sets flags, defined for the lifetime of the frame, that determine whether the frame is a root frame, a subframe, or an overlaid frame; once set, these flags cannot be changed.
A containing part must set the link status for any frame it embeds, even if the embedded part does not support links to its content. The containing part specifies a link status value based solely on the embedded frame's inclusion in links maintained by the containing part. A frame considers the link status of its containing frame when setting its own link status.

Methods
This section presents summary descriptions of the ODFrame methods grouped according to purpose, followed by detailed descriptions in alphabetical order.
Frame Hierarchy

AcquireContainingFrame
Returns a reference to a containing frame of this frame.
SetContainingFrame
Assigns the specified frame as the containing frame of this frame.
AcquirePart
Returns a reference to a part displayed in this frame.
ChangePart
Assigns a new part to this frame.
AcquireWindow
Returns a reference to the window this frame is displayed in.
SetWindow
Assigns a window to this frame.
IsSubframe
Returns a Boolean value that indicates whether this frame is a subframe of its containing frame.
SetSubframe
Specifies whether this frame is currently a subframe of its containing frame.
Frame Geometry

CreateShape
Creates a shape object.
AcquireFrameShape
Returns a reference to the frame shape of this frame.
ChangeFrameShape
Changes the frame shape of this frame.
AcquireUsedShape
Returns a reference to the used shape of this frame.
ChangeUsedShape
Assigns a used shape to this frame.
CreateTransform
Creates a transform object.
AcquireInternalTransform

Returns a reference to the internal transform of this frame.
ChangeInternalTransform

Changes the internal transform of this frame.
RequestFrameShape
Requests a new frame shape for this frame.
Frame Characteristics

IsFrozen
Returns a Boolean value that indicates whether this frame is bundled.
SetFrozen
Specifies whether this frame is currently bundled.
IsInLimbo
Returns a Boolean value that indicates whether this frame is removed from a part's content model.
SetInLimbo
Specifies whether this frame is to be removed from a part's content model.
IsOverlaid
Returns a Boolean value that indicates whether this frame is an overlaid frame.
IsRoot
Returns a Boolean value that indicates whether this frame is the root frame.
Closing and Removing Frames

Close
Prepares this frame to be removed from memory, but does not affect persistent storage.
Remove
Prepares this frame to be removed both from memory and persistent storage.
Frame Groups

GetFrameGroup
Returns the group ID of this frame.
SetFrameGroup
Assigns a group ID to this frame.
GetSequenceNumber
Returns the sequence number of this frame in its frame group.
ChangeSequenceNumber
Assigns a sequence number to this frame in its frame group.
Imaging

GetViewType
Returns this frame's view type.
SetViewType
Assigns the specified view type to this frame.
ChangeViewType
Changes the specified view type of this frame.
GetPresentation
Returns this frame's presentation.
SetPresentation
Assigns the specified presentation to this frame.
ChangePresentation
Changes the presentation of this frame.
DrawActiveBorder
Updates the active frame border of this frame.
Invalidate
Marks the specified area in this frame as in need of updating.
InvalidateActiveBorder
Marks the active frame border of this frame as in need of updating.
Validate
Marks the specified area in this frame as no longer in need of updating.
Linking

EditInLink
Returns a Boolean value that indicates whether the part maintaining a link destination (that includes this frame) can be found.
GetLinkStatus
Returns the link status of this frame.
ChangeLinkStatus
Changes the link status of this frame.
ContentUpdated
Notifies this frame's containing part that this frame's part has updated its content, so the containing part can update any link sources that it maintains.
Event Propagation

DoesPropagateEvents
Returns a Boolean value that indicates whether this frame propagates unhandled events to its containing part.
SetPropagateEvents
Specifies whether this frame should propagate unhandled events to its containing frame.
Facet Manipulation

CreateFacetIterator
Creates a frame-facet iterator object for the facets of this frame.
FacetAdded
Adds the facet to this frame's list of facets and notifies its part of the new facet.
FacetRemoved
Removes the facet from this frame's list of facets and notifies its part of the deletion.
Part Info

GetPartInfo
Returns the part info data for this frame.
SetPartInfo
Assigns part info data to this frame.
Content Extent

GetContentExtent
Gets the content extent of this frame.
ChangeContentExtent
Changes the content extent of this frame.
Drag and Drop

IsDragging
Returns a Boolean value that indicates whether this frame is currently being dragged.
SetDragging
Specifies whether this frame is currently being dragged.
IsDroppable
Returns a Boolean value that indicates whether this frame's part accepts drag-and-drop events in this frame.
SetDroppable
Specifies whether this frame's part accepts drag-and-drop events in this frame.

Methods
AcquireContainingFrame
AcquireFrameShape
AcquireInternalTransform
AcquirePart
AcquireUsedShape
AcquireWindow
ChangeContentExtent
ChangeFrameShape
ChangeInternalTransform
ChangeLinkStatus
ChangePart
ChangePresentation
ChangeSequenceNumber
ChangeUsedShape
ChangeViewType
Close
ContentUpdated
CreateFacetIterator
CreateShape
CreateTransform
DoesPropagateEvents
DrawActiveBorder
EditInLink
FacetAdded
FacetRemoved
GetContentExtent
GetFrameGroup
GetLinkStatus
GetPartInfo
GetPresentation
GetSequenceNumber
GetViewType
Invalidate
InvalidateActiveBorder
IsDragging
IsDroppable
IsFrozen
IsInLimbo
IsOverlaid
IsRoot
IsSubframe
Remove
RequestFrameShape
SetContainingFrame
SetDragging
SetDroppable
SetFrameGroup
SetFrozen
SetInLimbo
SetPartInfo
SetPresentation
SetPropagateEvents
SetSubFrame
SetViewType
SetWindow
Validate